********************************************************************************
* functions.do
* Purpose: Define user-written Stata programs used throughout the analysis.
*
* Programs defined here:
*   make_eventstudy  - Wrapper around coefplot that produces a standardized
*                      event-study figure for one or more regression models.
*                      Called from analyze_main.do, analyze_worker.do, etc.
********************************************************************************

//------------------------------------------------------------------------------
// make_eventstudy
//
// Produces a connected-line event-study plot using coefplot, then exports it
// as a PDF to the global $out directory.
//
// Syntax:
//   make_eventstudy <depvar_stub>, MODELS(<estnames>) COLORS(<colorlist>)
//       LABELS(<labellist>) FMT(<numfmt>) YLAB(<ylabel>) FIG(<figname>)
//       SUBFIG(<subfigname>)
//
// Arguments:
//   var      - Variable name stub (not used directly in the plot, for reference)
//   MODELS() - Space-separated list of stored estimate names (e.g. "es1 es2")
//   COLORS() - Space-separated list of Stata colors, one per model
//   LABELS() - Space-separated list of legend labels, one per model
//   FMT()    - Number format for y-axis (e.g. "%9.2fc")
//   YLAB()   - Y-axis label range in Stata notation (e.g. "-0.4(0.1)0.4")
//   FIG()    - Figure name prefix (e.g. "Figure2")
//   SUBFIG() - Figure name suffix (e.g. "A")
//   -> Output PDF saved as: $out/<FIG>_<SUBFIG>.pdf
//
// Event-study design:
//   - Time dummies ds_1..ds_13 span t = -6 to +5 relative to the event year
//   - ds_6 (t = -1, the year before the event) is the omitted base period
//   - ds_1, ds_2, ds_13 are excluded from the plot (boundary bins at t = -6, -5, +6)
//   - A vertical reference line is drawn between ds_6 (t=-1) and ds_7 (t=0)
//------------------------------------------------------------------------------
capture program drop make_eventstudy
program define make_eventstudy
    syntax anything(name=var) , MODELS(string) COLORS(string) LABELS(string) FMT(string) YLAB(string) FIG(string) SUBFIG(string)

    *-------------------------------------------------------------*
    *  Interaction terms to keep / drop in coefplot
    *  Keep all treated x ds_k interactions; drop the boundary bins
    *  ds_1 (t=-6), ds_2 (t=-5), and ds_13 (t=+6).
    *-------------------------------------------------------------*
    local included_var "1.treated#*"
    local excluded_var  "1.treated#1.ds_1 1.treated#1.ds_2 1.treated#1.ds_13"

    *-------------------------------------------------------------*
    *  Build coefplot coeflabel() option
    *  Maps each ds_k dummy to its readable event-time label (-5 to +5).
    *  ds_k corresponds to t = k - 7, so ds_2 -> -5, ..., ds_12 -> +5.
    *-------------------------------------------------------------*
    local labellist
    forvalues k = 2/12 {
        local tmp = `k' - 7
        local labellist `labellist' 1.treated#1.ds_`k' = "`tmp'"
        local labellist `labellist' 1.treated#0.ds_`k' = "`tmp'"
    }

    *-------------------------------------------------------------*
    *  Parse the space-separated MODELS, COLORS, and LABELS options
    *  into indexed locals: color1, color2, ..., label1, label2, ...
    *-------------------------------------------------------------*
    tokenize "`models'"
	local nmodels : word count `models'

    tokenize "`colors'"
    forvalues i = 1/`nmodels' {
        local color`i' ``i''
    }

    tokenize `"`labels'"'
    forvalues i = 1/`nmodels' {
        local label`i' ``i''
    }

    *-------------------------------------------------------------*
    *  Build coefplot p#() style options for each model:
    *    - connected line with circular markers
    *    - dashed capped-spike confidence intervals
    *  Also build the legend order (coefplot plots line then CI per model,
    *  so line for model i is at position 2*i in the legend).
    *-------------------------------------------------------------*
    local pstyles
    local legendorder

    forvalues i = 1/`nmodels' {
        local pstyles `pstyles' ///
            p`i'(mcol(`color`i'') msym(Oh) recast(connected) lc(`color`i'') ///
                 ciopts(recast(rcap) lp(dash) lc(`color`i'')))

        * coefplot draws: 1=line, 2=CI, 3=line, 4=CI, ...
        local lineindex = 2*`i'
        local legendorder `legendorder' `lineindex' "`label`i''"
    }

    *-------------------------------------------------------------*
    *  Create the event-study figure:
    *    - yline(0): horizontal reference at zero
    *    - xline(4.5): vertical line between t=-1 (ds_6) and t=0 (ds_7),
    *                  marking the event date
    *-------------------------------------------------------------*
    #delimit ;
    coefplot `models', vertical
        keep(`included_var') drop(`excluded_var')
        graphregion(color(white)) bgcolor(white) omitted

        `pstyles'

        ytitle("Coefficient Estimates [Year Before Event = 0]")
        xtitle("Year Relative to Event", size(medium))

        coeflabel(`labellist')

        legend(order(`legendorder')
               pos(6) rows(1)
               region(lstyle(solid) lcolor(black) fcolor(white)))

        yline(0, lcol(black) lp(solid))
        xline(4.5, lcol(black) lp(solid))

        ylabel(`ylab', angle(90) format(`fmt') grid gmax gmin)

        title("", size(large) color(black));
    #delimit cr

    *-------------------------------------------------------------*
    *  Export figure as PDF
    *-------------------------------------------------------------*
    graph export "$out/`fig'_`subfig'.pdf", replace

end

/* Example usage:
set trace on
#delimit ;
make_eventstudy emp,
    models("es1_emp es2_emp")
    colors("dknavy dkorange")
    labels("Acquirer Target")
    fmt("%9.2fc") ylab("-1(1)4")
	fig("Figure2") subfig("A");

#delimit cr
*/

//------------------------------------------------------------------------------
// make_eventstudy_decomp
//
// Produces a four-line event-study plot (total earnings, employer FE, match
// effect, direct effect) using twoway connected, then exports it as a PDF.
// No confidence intervals are drawn.
//
// Syntax:
//   make_eventstudy_decomp <depvar_stub>,
//       MTOTAL(<estname>)  MFE(<estname>)  MMET(<estname>)
//       FMT(<numfmt>)  YLAB(<ylabel>)  FIG(<figname>)
//
// Arguments:
//   MTOTAL() - stored estimate name for log(Earnings) regression
//   MFE()    - stored estimate name for Employer Fixed Effect regression
//   MMET()   - stored estimate name for Match Effect regression
//   FMT()    - number format for y-axis (e.g. "%9.2fc")
//   YLAB()   - y-axis label range in Stata notation (e.g. "-0.14(0.04)0.10")
//   FIG()    - figure name prefix (e.g. "FigureA10")
//   -> Output PDF: $out/<FIG>.pdf
//
// Event-study design (identical to make_eventstudy in functions.do):
//   - Time dummies ds_1..ds_13 span t = -6 to +5 relative to the event year
//   - ds_6 (t = -1, year before the event) is the omitted base period (= 0)
//   - ds_1 (t=-6), ds_2 (t=-5), ds_13 (t=+6) are excluded from the plot
//   - Vertical reference line is drawn at x = -0.5 (between t=-1 and t=0)
//   - ds_k covers t = k - 7, so ds_3 -> t=-4, ..., ds_12 -> t=+5
//
// Direct effect:
//   Direct_k = Beta_total_k - Beta_FE_k - Beta_match_k, for each k
//   (Residual portion of the total earnings change not attributable to
//    changes in the employer wage premium or the worker-firm match quality.)
//------------------------------------------------------------------------------
capture program drop make_eventstudy_decomp
program define make_eventstudy_decomp
    syntax anything(name=var), ///
        MTOTAL(string) MFE(string) MMET(string) ///
        FMT(string) YLAB(string) FIG(string)

    *-------------------------------------------------------------*
    *  Extract event-study coefficients from each stored estimate.
    *  k = 7..12  =>  t = k - 7  =>  t = 0, 1, 2, 3, 4, 5  (post-event)
    *  (k=6, t=-1 is the omitted base period; coefficient is 0 by construction
    *   but is not plotted -- the figure shows only the post-event window.)
    *-------------------------------------------------------------*

    * -- Total earnings model --
    estimates restore `mtotal'
    forvalues k = 7/12 {
        capture local b_total_k`k' = _b[1.treated#1.ds_`k']
        if _rc local b_total_k`k' = 0
    }

    * -- Employer Fixed Effect model --
    estimates restore `mfe'
    forvalues k = 7/12 {
        capture local b_fe_k`k' = _b[1.treated#1.ds_`k']
        if _rc local b_fe_k`k' = 0
    }

    * -- Match Effect model --
    estimates restore `mmet'
    forvalues k = 7/12 {
        capture local b_met_k`k' = _b[1.treated#1.ds_`k']
        if _rc local b_met_k`k' = 0
    }

    *-------------------------------------------------------------*
    *  Compute direct effect = total - FE - match, period by period
    *-------------------------------------------------------------*
    forvalues k = 7/12 {
        local b_direct_k`k' = `b_total_k`k'' - `b_fe_k`k'' - `b_met_k`k''
    }

    *-------------------------------------------------------------*
    *  Build a temporary dataset with one row per event-time period
    *  and plot using twoway connected
    *-------------------------------------------------------------*
    preserve
    clear
    set obs 6   // k = 3, 4, 5, 6, 7, 8, 9, 10, 11, 12

    gen t        = .
    gen b_total  = .
    gen b_fe     = .
    gen b_met    = .
    gen b_direct = .

    local i = 1
    forvalues k = 7/12 {
        local t_val = `k' - 7
        quietly replace t        = `t_val'          in `i'
        quietly replace b_total  = `b_total_k`k''  in `i'
        quietly replace b_fe     = `b_fe_k`k''     in `i'
        quietly replace b_met    = `b_met_k`k''    in `i'
        quietly replace b_direct = `b_direct_k`k'' in `i'
        local i = `i' + 1
    }

    sort t

    *-------------------------------------------------------------*
    *  Draw the event-study figure
    *    - Four connected lines, no confidence interval bands
    *    - yline(0): horizontal reference at zero
    *    - xline(-0.5): vertical line between t=-1 and t=0 (event date)
    *-------------------------------------------------------------*
    #delimit ;
    twoway
        area 		b_fe     t, fcolor(red) fintensity(inten20) color(red) ||
        area 		b_met    t, fcolor(green) fintensity(inten20) color(green) ||
        area	 	b_direct t, fcolor(blue%50) fintensity(inten20) color(blue) ||
		connected	b_total  t, lcolor(black) mcolor(black)

        yline(0, lcol(black) lp(solid))

        xlabel(0(1)5)
        ylabel(`ylab', angle(90) format(`fmt') grid gmax gmin)

        ytitle("log points")
        xtitle("Year Relative to Event", size(medium))

        legend(order(
                1 "Employer Fixed Effect"
                2 "Match Effect"
                3 "Direct Effect")
               pos(6) rows(2)
               region(lstyle(solid) lcolor(black) fcolor(white)))

        graphregion(color(white)) bgcolor(white)
        title("", size(large) color(black));
    #delimit cr

    graph export $out/`fig'.pdf, replace
    restore

end


// Example Usage:
// #delimit ;
// make_eventstudy_decomp t4earn,
//     mtotal("es_t4earn")
//     mfe("es_fe")
//     mmet("es_met")
//     fmt("%9.2fc") ylab("-0.2(0.05)0.10")
//     fig("FigureA10");
// #delimit cr
